home *** CD-ROM | disk | FTP | other *** search
/ Aminet 39 / Aminet 39 (2000)(Schatztruhe)[!][Oct 2000].iso / Aminet / comm / net / AMarquee.readme < prev    next >
Encoding:
Text File  |  2000-09-02  |  16.3 KB  |  285 lines
  1. Short:    V52.0 TCP Data Broadcast System (library & server)
  2. Author:   hakan@parting.nu (Håkan Parting & Jeremy Friesner)
  3. Uploader: hakan@parting.nu (Håkan Parting)
  4. Version:  52.0
  5. Type:     comm/net
  6. Requires: Workbench 2.04+, AmiTCP3.0b+ or compatible TCP stack
  7. Replaces: comm/net/AMarquee51.lha, comm/net/AMarquee50.lha
  8.  
  9. ----------------------------------------------------------------
  10.  
  11.                           AMARQUEE v52.0
  12.  
  13.                     (Released August 12th 2000)
  14.  
  15. ----------------------------------------------------------------
  16.  
  17.  
  18. The Problem: 
  19.  
  20.  You have a great idea for a killer multi-player Internet game 
  21.  or multi-user net app, but it's a total pain in the @)#$* to 
  22.  write all the TCP connection and data synchronization code 
  23.  you'll need to get it going.  So you put your idea on the 
  24.  back-burner and go play "Lemmings" instead.  And thus the 
  25.  Amiga is deprived of a fun Internet app.  D-oh!  :(
  26.  
  27. The Solution:  (well, okay, it's *a* solution, anyway)
  28.  
  29.  AMarquee is a system that handles all of the icky information 
  30.  distribution details for you, allowing you to concentrate on 
  31.  coding your application, rather than on which data goes into 
  32.  which socket when.  AMarquee consists of a shared library and
  33.  a TCP daemon, which work together to get your data where it
  34.  needs to be.  Your program calls simple amarquee.library
  35.  functions to broadcast your data, and waits on a provided
  36.  MsgPort for data from other hosts.  Easy!
  37.  
  38.  Version 49+ of amarquee.library may be used in more serious network
  39.  applications too, that cannot use the amarquee protocol, like FTP and HTTP
  40.  clients. This in the same easy fashioned way!
  41.  
  42. Features of amarquee.library (the shared library/API):
  43.  
  44.  - Programs written to use amarquee.library will work transparently
  45.    with Inet225, AmiTCP, Miami, or any other TCP stack that is 
  46.    "AmiTCP compatible".
  47.  - Has a simple API that requires no knowledge of multithreading 
  48.    techniques or socket programming to use.
  49.  - Each AMarquee connection you make automatically and transparently
  50.    starts a separate background execution thread, so your app will 
  51.    never have to block while data is sent or received.
  52.  - An arbitrary number of AMarquee connections may be active at once.
  53.  - Allows you to "subscribe" to data that interests you, so that
  54.    when the data on the server is changed you will be automatically 
  55.    notified.  You never need to poll for anything!
  56.  - An easy mechanism for sending messages to one or many other
  57.    AMarquee clients that are logged into the same server.
  58.  - Standard Amiga wildcarding is supported in all applicable functions.
  59.    This allows you to easily and succinctly refer to one host or data
  60.    item, or many, as appropriate.
  61.  - #includes for C, C++, and PCQ Pascal are included.
  62.  - ARexx accessible.  That is, ARexx scripts can use amarquee.library
  63.    through rexxamarquee.library for communications using the same API
  64.    that compiled C programs do.
  65.  - Example programs in C, C++, Pascal, and ARexx are included.
  66.  - Operation is almost totally asynchronous for efficiency, but
  67.    several easy synchronization methods are available if you need them.
  68.  - Can also be used for direct client-to-client connections and
  69.    for making inetd-launched or manually-launched daemon programs.
  70.  - Automatically detects when the computer on the other end of
  71.    the AMarquee connection has crashed or been shut down, even 
  72.    on idle connections.
  73.  - In addition it can connect to any TCP service, eg. HTTP and FTP, and it will
  74.    work in the same easy fashion like any other AMarquee connection.
  75.  
  76. Features of AMarqueed (the AmiTCP server):
  77.  
  78.  - Works with Inet225, AmiTCP, Miami, or any other TCP stack 
  79.    that is "AmiTCP compatible".
  80.  - Fully multithreaded design, with one server process per connection.
  81.  - Re-entrant code, to minimize memory usage.
  82.  - Data is stored in a filesystem-like tree structure for simplicity,
  83.    flexibility and efficiency.  Each client gets its own "home directory"
  84.    that it may write to or read from, and each client may also
  85.    read from the "home directories" of other clients.
  86.  - Efficient design minimizes CPU usage, net bandwidth, and execution time.
  87.  - Limits may be put on memory usage, number of connections, and/or 
  88.    which clients or apps may connect.  Only serve the hosts and apps
  89.    you want to serve!
  90.  - Supports data streaming to one or many clients at once.
  91.  - Data streaming and synchronization features let you be sure your 
  92.    data was read by all interested hosts before you update it again.
  93.  - Automatically detects and eliminates "dead" connections (e.g.
  94.    if the client computer was shut down without quitting politely)
  95.  - Server may be administered remotely by clients with "privileged"
  96.    status.
  97.  
  98. WHAT'S NEW IN VERSION 52.0:
  99. ( "-" = new feature, "*" = bug fix)
  100. V52.0: (Public release 12-Aug-2000) (amarquee.library v52.0, rexxamarquee.library v52.0, AMarqueed v51.0)
  101. *    This bug should have been fixed in v.51 but apperently wasn't :(
  102.      The QNew*Session() and QFreeSession() functions cleared the shared message port given
  103.      with the tag QSESSION_SHAREDMSGPORT.
  104.      Because of this misfunction there were problems when you created a new or freed an old
  105.      session while there were messages waiting in the message port. You should require at
  106.      least v.52 of amarquee.library when you use shared message ports.
  107.      Please understand that only one task, the one which created the shared message port, may
  108.      create and free sessions which are bound to the shared message port.
  109.  
  110.      For any sessions please also understand that you must make sure that only one task at
  111.      one time use a specific session. This apply to all the Q*Op() functions, which could be
  112.      called from several tasks if the calls are serialized.
  113.      QFreeSession() may only be called from the task which owns the session, i.e. the task
  114.      which created the session or have taken over a session with QReattachSession().
  115.  
  116. V51.4: (Public release 06-Aug-2000) (amarquee.library v51.4, rexxamarquee.library v51.0, AMarqueed v51.0)
  117. *    The qm_ActualLen in QMessage could sometimes be wrong with Socket Sessions from v50.
  118.      This probably didn't cause any trouble because you normally don't use that field.
  119. *    Fixed some rare memory leakage.
  120. -    Added a new feature for Socket-Sessions. Previously it was not very easy
  121.      to use these sessions. The data received from the other host could be
  122.      divided into several QMessages. And you couldn't explicitely tell AMarquee
  123.      to return only entire application transfer units. Instead you had to buffer
  124.      the data and copy all QMessages containing one transfer unit into your buffer.
  125.  
  126.      To solve this problem I've added a couple of tags to use with QNewSocket*Session().
  127.      QRAWSESSION_PROTOCOLSTOPHOOK, QRAWSESSION_RECEIVE_EXCEEDING_DATA and
  128.      QRAWSESSION_PROTOCOLSTOPHOOK_USERDATA. Now communication with hosts not
  129.      using the AMarquee protocol should be as simple as if they did. 
  130.      Take a look on the new examples named geturl_Hook1.c and geturl_Hook2.c.
  131.       
  132. *    The QNew*Session() and QFreeSession() functions cleared the shared message port given
  133.      with the tag QSESSION_SHAREDMSGPORT.
  134.      Because of this misfunction there were problems when you created a new or freed an old
  135.      session while there were messages waiting in the message port. You should require at
  136.      least v.51 of amarquee.library when you use shared message ports.
  137.      Please understand that only one task, the one which created the shared message port, may
  138.      create and free sessions which are bound to the shared message port.
  139.  
  140.      For any sessions please also understand that you must make sure that only one task at
  141.      one time use a specific session. This apply to all the Q*Op() functions, which could be
  142.      called from several tasks if the calls are serialized.
  143.      QFreeSession() may only be called from the task which owns the session, i.e. the task
  144.      which created the session or have taken over a session with QReattachSession().
  145.  
  146. *    There were some trouble if you had set AMARQUEED_ALLOWBROWSE and AMARQUEED_RESTRICTBROWSE
  147.      on the AMarqueed server. This bug is fixed in this version of AMarqueed.
  148.      1. If a client program from one host connected more than once to amarqueed, the new client
  149.      is supposed to take over and kill the old client. Instead the old client got killed and the
  150.      new one failed to connect with error code QERROR_ACCESS_DENIED (Server Refused Connection).
  151.      2. Occasionally the host path set with AMARQUEED_RESTRICTBROWSE got banned from the server.
  152.      Both these problems happened on the AmiComSys/AMarquee server acs.hostile.cx. The last one
  153.      occured about once a month. That's the reason for the recent down times.
  154. -    Improved documentation and added a standard autodoc for amarquee.library to the distribution.
  155.  
  156. V50.11a: (Public Release 8-Apr-2000) (amarquee.library v50.11, rexxamarquee.library v50.6, AMarqueed v49.7)
  157. -    Added a amarquee.lib for use with vbccm68k C-compiler.
  158. -    Modified the AMarquee_protos.h file to make it work with vbcc and other compilers.
  159. -    AMarquee is Donationware. Now you could register online. See the distribution section in the
  160.      guide for more info. 
  161.  
  162. V50.11: (Public Release 19-Mar-2000) (amarquee.library v50.11, rexxamarquee.library v50.6, AMarqueed v49.7)
  163. -    amarquee.library now returns larger packets with a Socket-Session connection,
  164.      instead of several small packets.
  165. -    Added function QSetMaxRawBufSize() to library. Use it to set the maximum buffer
  166.      size that shall be used with a Socket Session. This is the maximum size of the
  167.      QMessage you receive. As an option you can use the tag named QRAWSESSION_MAXBUFFERSIZE
  168.      with the QNewSocket*Session() call.
  169. -    Updated rexxamarquee.library with the new function. Rexxamarquee.library v.50x
  170.      requires amarquee.library v.50 or better.
  171. -    Modified QNewSession, QNewSessionAsync, QNewHostSession, QNewServerSession().
  172.      They now also take an additional argument with a tag list.
  173.      Old programs compiled for v.49 or less will still work.
  174.      New programs compiled for v.50 won't work with v.49 or less, so
  175.      the minimum version to require with the protos, fd, and pragmas which are
  176.      in the v.50+ AMarquee-package is 50.
  177.      Old source code using the new header-files must be updated.
  178. -    A tag, QSESSION_ERRORCODEPTR, was added. Set it to a pointer to a LONG-variable
  179.      where you want the error code to be copied. This is needed because QNewSession() returns
  180.      NULL when it fails, i.e. you can't use QFreeSession() to find out why.
  181. -    Dropped support for the INET225 version of amarquee.library. Is anybody using it?
  182. -    Changed the error code which is returned by QFreeSession() or copied to the
  183.      QSESSION_ERRORCODEPTR variable when a connection to a server port failed.
  184.      When the QNewSocketSession(Async) function is used the return code is QERROR_NO_TCPSERVER
  185.      instead of QERROR_NO_SERVER. 
  186. -    QCreateSharedMessagePort(), QDeleteSharedMessagePort() functions added to library.
  187. -    Added the tag QSESSION_SHAREDMSGPORT.
  188. -    Added example amarqueesharedmp.c to show how to use the new shared message port functions.
  189. *    The qm_Path of the QMessage received when a asynchronious connection have been established
  190.      only contained the host name. It shall also contain the program name, like /hostname/progname,
  191.      when QNewSessionAsync() was used.
  192. -    AMarqueed was not updated in this release.
  193.  
  194.  
  195. ============================= Archive contents =============================
  196.  
  197. Original  Packed Ratio    Date     Time    Name
  198. -------- ------- ----- --------- --------  -------------
  199.     4008    1357 66.1% 14-Feb-99 19:10:12  AMarquee.info
  200.   214668   59265 72.3% 12-Aug-00 21:11:52 +AMarquee.guide
  201.     1542    1096 28.9% 10-Apr-98 12:24:46 +AMarquee.guide.info
  202.      152     152  0.0% 12-Aug-00 21:13:16 +AMarquee.guide.sig
  203.    26188   14315 45.3% 12-Aug-00 21:11:16 +amarquee.library
  204.      152     152  0.0% 12-Aug-00 21:13:54 +amarquee.library.sig
  205.    11457    4392 61.6% 12-Aug-00 21:11:58 +AMarquee.readme
  206.      835     268 67.9% 10-Apr-98 12:24:44 +AMarquee.readme.info
  207.      152     152  0.0% 12-Aug-00 21:13:30 +AMarquee.readme.sig
  208.    46528   23955 48.5% 06-Aug-00 21:18:46 +AMarqueed
  209.      152     152  0.0% 06-Aug-00 21:24:06 +amarqueed.sig
  210.   134612   32651 75.7% 12-Aug-00 21:12:14 +amarquee.doc
  211.     4123    1604 61.0% 10-Apr-98 12:24:48 +EditTextFile.rexx
  212.    11260    6410 43.0% 06-Aug-00 21:21:50 +AmarqueeDebug
  213.     7426    2513 66.1% 06-Aug-00 21:21:50 +amarqueedebug.c
  214.     6753    2323 65.6% 10-Apr-98 12:24:50 +amarqueedebug.cpp
  215.     7058    2305 67.3% 06-Aug-00 21:21:50 +amarqueedebug.rexx
  216.    13084    7303 44.1% 06-Aug-00 21:21:50 +AMarqueeDebugMultiThread
  217.     9720    3285 66.2% 06-Aug-00 21:21:50 +AMarqueeDebugMultiThread.c
  218.     9264    5541 40.1% 06-Aug-00 21:21:50 +amarqueehost
  219.     4180    1564 62.5% 06-Aug-00 21:21:50 +amarqueehost.c
  220.     6383    2116 66.8% 06-Aug-00 21:21:50 +amarqueehost.rexx
  221.    11936    6971 41.5% 06-Aug-00 21:21:50 +amarqueeserver
  222.     5312    1922 63.8% 06-Aug-00 21:21:50 +AMarqueeServer.c
  223.     8168    4997 38.8% 06-Aug-00 21:21:50 +amarqueesharedmp
  224.     5296    1632 69.1% 06-Aug-00 21:21:50 +amarqueesharedmp.c
  225.     9340    5601 40.0% 06-Aug-00 21:21:50 +amarqueesocketdebug
  226.     4245    1751 58.7% 06-Aug-00 21:21:50 +amarqueesocketdebug.c
  227.     9024    5414 40.0% 06-Aug-00 21:21:50 +amarqueesockethost
  228.     3379    1417 58.0% 06-Aug-00 21:21:50 +amarqueesockethost.c
  229.      656     319 51.3% 06-Aug-00 21:21:50 +amarqueetags.o
  230.     7468    4788 35.8% 06-Aug-00 21:21:52 +BounceCount
  231.     2915    1169 59.8% 06-Aug-00 21:21:52 +BounceCount.c
  232.      522     275 47.3% 06-Aug-00 21:21:52 +dmakefile
  233.      494     262 46.9% 10-Apr-98 12:24:52 +dmakefile.bak
  234.     7600    4812 36.6% 06-Aug-00 21:21:52 +geturl
  235.     3240    1351 58.3% 06-Aug-00 21:21:52 +GetURL.c
  236.     2788    1247 55.2% 06-Aug-00 21:21:52 +geturl.rexx
  237.     8244    5104 38.0% 06-Aug-00 21:21:52 +geturl_hook1
  238.     7439    2578 65.3% 06-Aug-00 21:21:52 +GetURL_Hook1.c
  239.     7792    4924 36.8% 06-Aug-00 21:21:52 +geturl_Hook2
  240.     4588    1855 59.5% 06-Aug-00 21:21:52 +GetURL_Hook2.c
  241.     2431    1104 54.5% 06-Aug-00 21:21:52 +killclients.rexx
  242.    10552    6495 38.4% 06-Aug-00 21:21:52 +MiniIRC
  243.     6544    2271 65.2% 06-Aug-00 21:21:52 +MiniIRC.c
  244.     3336    1984 40.5% 06-Aug-00 21:21:52 +PascalTest
  245.     1147     506 55.8% 06-Aug-00 21:21:52 +PascalTest.p
  246.     7052    4500 36.1% 06-Aug-00 21:21:52 +RemoveTest
  247.     2551    1039 59.2% 06-Aug-00 21:21:52 +RemoveTest.c
  248.     9400    5793 38.3% 06-Aug-00 21:21:52 +SillyGame
  249.     8219    2592 68.4% 06-Aug-00 21:21:52 +SillyGame.c
  250.     7472    4774 36.1% 06-Aug-00 21:21:52 +StreamCheck
  251.     3137    1245 60.3% 06-Aug-00 21:21:52 +StreamCheck.c
  252.     7336    4699 35.9% 06-Aug-00 21:21:52 +Streamgen
  253.     2617    1093 58.2% 06-Aug-00 21:21:52 +streamgen.c
  254.     7528    4788 36.3% 06-Aug-00 21:21:52 +Synctest
  255.     3255    1305 59.9% 06-Aug-00 21:21:52 +SyncTest.c
  256.     2649    1169 55.8% 06-Aug-00 21:21:52 +sysmessage.rexx
  257.     5303    1363 74.2% 19-Mar-00 00:25:18 +AMarquee49_protos.h
  258.     6303    1558 75.2% 08-Apr-00 13:18:32 +AMarquee_protos.h
  259.     1504     330 78.0% 19-Mar-00 00:25:18 +amarqueetags.c
  260.      656     319 51.3% 19-Mar-00 00:25:18 +amarqueetags.o
  261.     1584     507 67.9% 19-Mar-00 00:25:18 +AMarquee49_lib.fd
  262.     1795     575 67.9% 19-Mar-00 00:25:18 +AMarquee_lib.fd
  263.     8455    1436 83.0% 19-Mar-00 00:25:18 +AMarquee.h
  264.     7072    1265 82.1% 19-Mar-00 00:25:18 +AMarquee49.h
  265.     8708    1610 81.5% 08-Apr-00 13:17:34 +amarquee.lib
  266.     6297    2496 60.3% 06-Aug-00 21:11:16 +AMarquee.h
  267.     4161    1701 59.1% 19-Mar-00 00:25:18 +AMarquee49.h
  268.     2177     522 76.0% 19-Mar-00 00:25:18 +AMarquee49_pragmas.h
  269.     2548     597 76.5% 19-Mar-00 00:25:18 +AMarquee_pragmas.h
  270.      301     195 35.2% 19-Mar-00 00:25:18 +AMarquee.h
  271.      305     197 35.4% 19-Mar-00 00:25:18 +AMarquee49.h
  272.      409     217 46.9% 19-Mar-00 00:25:18 +AMarquee.h
  273.      413     221 46.4% 19-Mar-00 00:25:18 +AMarquee49.h
  274.    13339    2949 77.8% 19-Mar-00 00:25:08 +Session.h
  275.    12182    2870 76.4% 19-Mar-00 00:25:08 +Session49.h
  276.    23923    5949 75.1% 19-Mar-00 00:24:42 +Install_AMarquee
  277.      612     329 46.2% 10-Apr-98 12:24:48 +Install_AMarquee.info
  278.    10298    2903 71.8% 06-Aug-00 21:18:18 +AMarquee.i
  279.     6024     817 86.4% 19-Mar-00 00:24:58 +AMarquee.lib
  280.     1318     910 30.9% 06-Aug-00 21:24:48 +public-pgp-key.asc
  281.    13040    6774 48.0% 12-Aug-00 21:11:24 +rexxamarquee.library
  282.      152     152  0.0% 12-Aug-00 21:14:10 +rexxamarquee.library.sig
  283. -------- ------- ----- --------- --------
  284.   854248  315379 63.0% 30-Aug-100 21:30:32   84 files
  285.